JBoss.orgCommunity Documentation
JBoss Communications SS7 stack at its core requires only Java if you are using only M3UA
.
However if you plan to use dahdi
or dialogic
SS7 hardware, respective SS7 cards
needs to be installed on the server along with native libraries.
A simple way to get started is to download and install binary. This will provide you with all the dependencies you need to get going. You can obtain binary release from NOT AVAILABLE
The JBoss Communications SS7 Stack binary is broken down into a few modules.
The following is a description of the important services and libraries that make up JBoss Communications SS7 Stack
asn
: Abstract Syntax Notation One (ASN.1) library is used by various JBoss Communications SS7 Stack
protocols to encode/decode the structured data exchanged between Signaling Point over networks. To know more about asn library refer to
document included with asn. Applications using any of the JBoss Communications SS7 Stack User Protocols may never need to call asn API directly,
however it must be in classpath as JBoss Communications SS7 Stack User Protocols refers this library.
ss7
: ss7 contains the service that is deployed in JBoss AS and libraries that end applications refers to.
It also includes JBoss Communications Signaling Gateway.
The sub-modules included in ss7 are
docs
: User guide for JBoss Communications SS7 Stack
mobicents-sgw
: Standalone Signaling Gateway as explained in section
Section 2.4, “JBoss Communications Signaling Gateway”
mobicents-sgw binary has following layout:
mobicents-ss7-service
: SS7 service is the core engine as explained in section
Section 2.2, “SS7 Service”
mobicents-ss7-service binary has following layout:
native
: native libraries component to interact with SS7 Card installed on server, runtime component.
As of now native libraries are compiled only for linux OS. However if you plan to use M3UA
there is
no dependency on OS as everything is 100% java.
protocols
: The JBoss Communications SS7 Stack User Protocols libraries. Your application would directly
call the API's exposed by these libraries. Depending on application you may be either interested in TCAP
,
MAP
or both or ISUP
libraries
shell
: the Command Line Interface (CLI) module to manage the JBoss Communications SS7 Stack.
Refer Chapter 5, Shell Command Line to understand how to use shell
Binary release has following layout:
The upper layers of Mobicents SS7 viz., TCAP, MAP depends on JBoss Communications SS7 Service and JBoss Communications SS7 Service must be installed before upper layers can be used. The JBoss Communications SS7 Service binary requires that you have JBoss Application Server installed and JBOSS_HOME system property set. To know further details on setting JBOSS_HOME look Appendix B, Setting the JBOSS_HOME Environment Variable
Once JBOSS_HOME is properly set, use ant to deploy the mobicents-ss7-service, shell scripts and shell library.
Ant 1.6 (or higher) is used to install the binary. Instructions for using Ant, including install, can be found at http://ant.apache.org/
[usr]$ cd ss7-1.0.0.BETA10/ss7 [usr]$ ant deploy
To undeploy these services
[usr]$ cd ss7-1.0.0.BETA10/ss7 [usr]$ ant undeploy
While above steps will deploy the necessary ss7 service and shell components, the java.library.path
should be set to point the directory containing native component or should be copied to JBoss native library path manually.
This step is only required if you are using the SS7 board on server.
Starting or stopping JBoss Communications SS7 Service is no different than starting or stopping JBoss Application Server
Once installed, you can run server by executing the run.sh (Unix) or run.bat (Microsoft Windows)
startup scripts in the <install_directory>/bin
directory (on Unix or Windows).
If the service started properly you should see following lines in the Unix terminal or Command Prompt depending on your environment:
23:22:26,079 INFO [LinksetManager] SS7 configuration file path /home/abhayani/workarea/mobicents/jboss-5.1.0.GA/server/default/data/linksetmanager.xml 23:22:26,141 INFO [LinksetManager] Started LinksetManager 23:22:26,199 INFO [SS7Service] Starting SCCP stack... 23:22:26,229 INFO [SccpStackImpl] Starting ... 23:22:26,230 INFO [RouterImpl] SCCP Router configuration file: /home/abhayani/workarea/mobicents/jboss-5.1.0.GA/server/default/deploy/mobicents-ss7-service/sccp-routing.txt 23:22:26,261 INFO [SS7Service] SCCP stack Started. SccpProvider bound to java:/mobicents/ss7/sccp 23:22:26,261 INFO [ShellExecutor] Starting SS7 management shell environment 23:22:26,270 INFO [ShellExecutor] ShellExecutor listening at /127.0.0.1:3435 23:22:26,270 INFO [SS7Service] [[[[[[[[[ Mobicents SS7 service started ]]]]]]]]]
If you have started ss7-1.0.0.BETA10 for the first time, SS7
is not configured.
You need to use Shell Client to connect to ss7-1.0.0.BETA10 as defined in
Chapter 5, Shell Command Line . With CLI
you can configure how service interacts with SS7 network, that is you configure either installed SS7 card and its native library\
, or M3UA
layer.
Once the configured, the state and configuration of SS7
is persisted which stands server re-start.
You can shut down the server(s) by executing the shutdown.sh -s
(Unix) or
shutdown.bat -s
(Microsoft Windows) scripts in the <install_directory>/bin
directory (on Unix or Windows). Note that if you properly stop the server, you will see the following three lines as the
last output in the Unix terminal or Command Prompt:
[Server] Shutdown complete Halting VM
Configuration is done through an XML descriptor named jboss-beans.xml
and is
located at $JBOSS_HOME/server/profile_name/deploy/mobicents-ss7-service/META-INF
, where
profile_name is the server profile name.
The JBoss Communications SS7 Layer 4 (SCCP, ISUP
) leverages either of following MTP
layers to exchange signalling messages with remote signalling points
M3UA
dahdi
dialogic
The ss7 service will be configured with either of these services.
ClientM3UAProcess
is only needed if the underlying SS7 service will leverage M3UA
.
ClientM3UAProcess
acts as remote Signaling Gateway Process. M3UAShellExecutor
accepts the M3UA
commands and executes necessary operations. ClientM3UAManagement
contains the list of Application Server (AS) (and list of Application Server Process (ASP) within each AS) connecting
to external Signaling Gateway (SG) and also manages them.
<!-- ==================================================================== -->
<!-- M3UA -->
<!-- ClientM3UAManagement is managing the ASP side commands -->
<!-- ==================================================================== -->
<bean name="ClientM3UAManagement"
class="org.mobicents.protocols.ss7.m3ua.impl.as.ClientM3UAManagement">
<property name="persistDir">${jboss.server.data.dir}</property>
</bean>
<bean name="M3UAShellExecutor"
class="org.mobicents.protocols.ss7.m3ua.impl.oam.M3UAShellExecutor">
<property name="m3uaManagement">
<inject bean="ClientM3UAManagement" />
</property>
</bean>
<bean name="Mtp3UserPart"
class="org.mobicents.protocols.ss7.m3ua.impl.as.ClientM3UAProcess">
<property name="clientM3UAManagement">
<inject bean="ClientM3UAManagement" />
</property>
</bean>
ClientM3UAManagement
when started looks for file's m3ua-client.xml
and
m3ua-clientroute.xml
. The m3ua-client.xml
contains serialized information about
AS and ASP configured for this ClientM3UAProcess
. The m3ua-clientroute.xml
contains
serialized information about defined routes.
Route maintains the availability status of a remote Point Code in the SS7 network via one or more Signaling Gateways. Application Hosts connecting to Signaling Gateways will require the configuration of Routes for each Remote Signaling Point Code they wish to communicate with.
Dahdi
based MTP layer will only be used when you have installed dahdi based SS7 hardware (Sangoma or Diguim cards).
DahdiLinksetFactory
is responsible to create
new instances of corresponding DahdiLinkset
when instructed by LinksetManager
.
DahdiLinksetFactory
<bean name="DahdiLinksetFactory"
class="org.mobicents.ss7.hardware.dahdi.oam.DahdiLinksetFactory">
</bean>
LinksetFactoryFactory
is just a call-back class listening for new factories deployed
and maintains Map of available factory name vs factory. You should never touch this bean.
LinksetManager
is responsible for managing Linkset
and Link
.
<!-- ================================================ -->
<!-- Linkset manager Service -->
<!-- ================================================ -->
<bean name="LinksetManager"
class="org.mobicents.ss7.linkset.oam.LinksetManager">
<property name="linksetFactoryFactory">
<inject bean="LinksetFactoryFactory" />
</property>
<property name="persistDir">${jboss.server.data.dir}</property>
</bean>
<bean name="LinksetExecutor"
class="org.mobicents.ss7.linkset.oam.LinksetExecutor">
<property name="linksetManager">
<inject bean="LinksetManager" />
</property>
</bean>
LinksetManager when started looks for file linksetmanager.xml
containing serialized information about
underlying linksets and links. The directory path is configurable by changing value of persistDir
property.
linksetmanager.xml
should never be edited by hand. Always use Shell Client to connect to
JBoss Communications SS7 Stack and execute commands.
LinksetExecutor
accepts the linkset
commands and executes necessary operations.
Dialogic
based MTP layer will only be used when you have installed Dialogic cards.
DialogicMtp3UserPart
communicates with Dialogic hardware. Its asumed here that MTP3 and MTP2 is leveraged from
Dialogic stack either on-board or on-host.
<!-- ==================================================================== -->
<!-- Dialogic Mtp3UserPart -->
<!-- ==================================================================== -->
<bean name="Mtp3UserPart" class="org.mobicents.ss7.hardware.dialogic.DialogicMtp3UserPart">
<property name="sourceModuleId">61</property> <property name="destinationModuleId">34</property>
</bean>
sourceModuleId
is source module id and should match with configured in
system.txt used by dialogic drivers. Here 61 is assigned for Mobicents process. destinationModuleId
is destination module id. 34 is Dialogic MTP3 module id.
ShellExecutor
is responsible for listening to incoming command. Received commands are executed on local resources to
perform actions like creation and management of SCCP
routing rule, creation and management of Linkset
,
management of M3UA
stack.
<!-- ================================================ -->
<!-- Shell Service -->
<!-- ================================================ -->
<!-- Define Shell Executor -->
<bean name="ShellExecutor"
class="org.mobicents.ss7.ShellExecutor">
<property name="address">${jboss.bind.address}</property>
<property name="port">3435</property>
<!-- LinksetExecutor required only if dahdi based hardware is installed. -->
<property name="linksetExecutor">
<inject bean="LinksetExecutor" />
</property>
<!-- M3UAShellExecutor required only if M3UA will be leveraged. -->
<property name="m3UAShellExecutor">
<inject bean="M3UAShellExecutor" />
</property>
<!-- To manage SCCP resource and rules -->
<property name="sccpExecutor">
<inject bean="SccpExecutor" />
</property>
</bean>
By default ShellExecutor listens at jboss.bind.address
and port 3435
.
You may set the address
property to any valid IP address that your host is assigned.
The shell commands are exchanged over TCP/IP.
To understand JBoss bind options look at Installation_And_Getting_Started_Guide
As name suggests SccpStack
initiates the SCCP stack routines.
Stack has following properties:
property specifies the local signaling point code.
specifies the network indicator that forms the part of service information octet (SIO)
manages the route for SCCP. When Router is started it looks for file sccprouter.xml
containing the serialized information about routes configured. The directory path is configurable by changing value of
persistDir
property
manages the remote resource for SCCP, for example Remote Subsystem Number and
Remote Signalling Pointcode. When SccpResource is started it looks for file sccpresource.xml
containing the serialized information about resources configured. The directory path is configurable by changing value of
persistDir
property
specifies SS7 Level 3 to be used as transport medium( be it SS7 card or M3UA)
SccpExecutor
accepts sccp
commands and executes necessary operations
SccpProvider
is bound to JNDI by SS7 Service and is used by upper layers
<!-- ==================================================================== -->
<!-- SCCP Router Service -->
<!-- ==================================================================== -->
<!--Define Router for SCCP -->
<bean name="Router" class="org.mobicents.protocols.ss7.sccp.impl.router.Router">
<property name="persistDir">${jboss.server.data.dir}</property>
</bean>
<bean name="SccpResource" class="org.mobicents.protocols.ss7.sccp.impl.SccpResource">
<property name="persistDir">${jboss.server.data.dir}</property>
</bean>
<bean name="SccpExecutor"
class="org.mobicents.protocols.ss7.sccp.impl.oam.SccpExecutor">
<property name="router">
<inject bean="Router" />
</property>
<property name="sccpResource">
<inject bean="SccpResource" />
</property>
</bean>
<bean name="SccpStack" class="org.mobicents.protocols.ss7.sccp.impl.SccpStackImpl">
<property name="localSpc">2</property>
<property name="ni">2</property>
<property name="router">
<inject bean="Router" />
</property>
<property name="sccpResource">
<inject bean="SccpResource" />
</property>
<property name="mtp3UserPart">
<inject bean="Mtp3UserPart" />
</property>
</bean>
<bean name="SccpProvider"
class="org.mobicents.protocols.ss7.sccp.impl.SccpProviderImpl">
<constructor factoryMethod="getSccpProvider">
<factory bean="SccpStack" />
</constructor>
</bean>
SS7Service
acts as core engine binding all the components together.
To get holistic view of SS7 Service look at Section 2.2, “SS7 Service”
<!-- ==================================================================== -->
<!-- Mobicents SS7 Service -->
<!-- ==================================================================== -->
<bean name="SS7Service" class="org.mobicents.ss7.SS7Service">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name=
"org.mobicents.ss7:service=SS7Service",
exposedInterface=org.mobicents.ss7.SS7ServiceMBean.class,
registerDirectly=true)</annotation>
<property name="jndiName">java:/mobicents/ss7/sccp</property>
<property name="stack">
<inject bean="SccpProvider" />
</property>
</bean>
SS7 service binds SccpProvider to JNDI java:/mobicents/ss7/sccp
.
The JNDI name can be configured to any valid JNDI name specific to your application.
JBoss Communications Signaling Gateway Binary doesn't require any additional steps. You may copy mobicents-sgw
to any folder of your choice.
In the Linux terminal or Windows command prompt, the JBoss Communications Signaling Gateway has started successfully if the last line of output is similar to the following
15:51:18,247 INFO [MainDeployer] [[[[[[[[[ Mobicents Signaling Gateway: release.version=1.0.0.BETA10 Started ]]]]]]]]]
Procedure 3.1. Running the JBoss Communications Signaling Gateway on Linux
Change the working directory to installation directory (the one in which the zip file's contents was extracted to)
downloads]$ cd "mobicents-ss7-<version>/ss7/mobicents-sgw"
(Optional) Ensure that the
bin/run.sh
start script is executable.
mobicents-sgw$ chmod +x bin/run.sh
Execute the
run.sh
Bourne shell script.
mobicents-sgw$ ./bin/run.sh
Procedure 3.2. Running the JBoss Communications Signaling Gateway on Windows
Using Windows Explorer, navigate to the bin
subfolder in the installation directory.
The preferred way to start the JBoss Communications Signaling Gateway is from the Command Prompt. The command line interface displays details of the startup process, including any problems encountered during the startup process.
Open the Command Prompt via the Start menu and navigate to the correct folder:
C:\Users\<user>\My Downloads>cd "mobicents-ss7-<version>\ss7\mobicents-sgw"
Start the Gateway by executing one of the following files:
run.bat
batch file:
C:\Users\<user>\My Downloads\mms-standalone<version>>bin\run.bat
Using run.sh
without any arguments binds the gateway to 127.0.0.1
.
To bind gateway to different ip, pass the ip address as value to -b
command line option.
For example to bind the server to 115.252.103.220
mobicents-sgw$ ./bin/run.sh -b 115.252.103.220
Configuration is done through an XML descriptor named sgw-beans.xml
and is
located at mobicents-sgw/deploy
,
Signaling Gateway Process that contains the list of Remote Application Server (Rem AS) (and list
of Remote Application Server Process (Rem ASP) within each rem AS) connecting to external Application Server (AS).
M3UAShellExecutor
accepts the M3UA
commands and executes necessary operations.
<!-- ================================================ -->
<!-- Signalling Gateway Process Service -->
<!-- ================================================ -->
<bean name="SgpImpl"
class="org.mobicents.protocols.ss7.m3ua.impl.sg.SgpImpl">
<constructor>
<parameter>${sgw.bind.address}</parameter>
<parameter>3434</parameter>
</constructor>
</bean>
<bean name="M3UAShellExecutor"
class="org.mobicents.protocols.ss7.m3ua.impl.oam.M3UAShellExecutor">
<property name="sgp">
<inject bean="SgpImpl" />
</property>
</bean>
SgpImpl
listens at ip ${sgw.bind.address}
and port 3434
for incoming
request from ASP.
Concrete implementation of LinksetFactory
is responsible to create
new instances of corresponding Linkset
when instructed by LinksetManager
.
JBoss Communications Signaling Gateway defines two linkset factories :
DahdiLinksetFactory
<bean name="DahdiLinksetFactory"
class="org.mobicents.ss7.hardware.dahdi.oam.DahdiLinksetFactory">
</bean>
DialogicLinksetFactory
<bean name="DialogicLinksetFactory"
class="org.mobicents.ss7.hardware.dialogic.oam.DialogicLinksetFactory">
</bean>
Its highly unlikely that you would require both the factories on same gateway. If you have dahdi
based
SS7 card installed, keep DahdiLinksetFactory
and remove other. If you have dialogic
based
SS7 card installed, keep DialogicLinksetFactory
and remove other.
LinksetFactoryFactory
is just a call-back class listening for new factories deployed
and maintains Map of available factory name vs factory. You should never touch this bean.
LinksetManager
is responsible for managing Linkset
and Link
.
<!-- ================================================ -->
<!-- Linkset manager Service -->
<!-- ================================================ -->
<bean name="LinksetManager"
class="org.mobicents.ss7.linkset.oam.LinksetManager">
<property name="linksetFactoryFactory">
<inject bean="LinksetFactoryFactory" />
</property>
<property name="persistDir">${linkset.persist.dir}</property>
</bean>
<bean name="LinksetExecutor"
class="org.mobicents.ss7.linkset.oam.LinksetExecutor">
<property name="linksetManager">
<inject bean="LinksetManager" />
</property>
</bean>
LinksetManager when started looks for file linksetmanager.xml
containing serialized information about
underlying linksets and links. The directory path is configurable by changing value of persistDir
property.
linksetmanager.xml
should never be edited by hand. Always use Shell Client to connect to
JBoss Communications Signaling Gateway and execute commands.
LinksetExecutor
accepts the linkset
commands and executes necessary operations.
ShellExecutor
is responsible for listening to incoming command. Received commands are executed on local resources to
perform actions like creation and management of Linkset
,
management of M3UA
stack.
<!-- ================================================ -->
<!-- Shell Service -->
<!-- ================================================ -->
<bean name="ShellExecutor"
class="org.mobicents.ss7.sgw.ShellExecutor">
<property name="address">${sgw.bind.address}</property>
<property name="port">3436</property>
<property name="linksetExecutor">
<inject bean="LinksetExecutor" />
</property>
<property name="m3UAShellExecutor">
<inject bean="M3UAShellExecutor" />
</property>
</bean>
By default ShellExecutor listens at sgw.bind.address
and port 3436
.
You may set the address
property to any valid IP address that your host is assigned.
The shell commands are exchanged over TCP/IP.
SignalingGateway
acts as core engine binding all the components together.
<!-- ================================================ -->
<!-- Mobicents Signaling Gateway -->
<!-- ================================================ -->
<bean name="SignalingGateway"
class="org.mobicents.ss7.sgw.SignalingGateway">
<property name="shellExecutor">
<inject bean="ShellExecutor" />
</property>
<property name="nodalInterworkingFunction">
<inject bean="NodalInterworkingFunction" />
</property>
</bean>
The NodalInterworkingFunction
sits between the SS7 netwrok and IP network and routes messages
to/from both the MTP3 and the M3UA layer, based on the SS7 DPC or DPC/SI address information
JBoss Communications SS7 Stack is an open source project, instructions for building from source are part of the manual! Building from source means you can stay on top with the latest features. Whilst aspects of JBoss Communications SS7 Stack are quite complicated, you may find ways to become contributors.
JBoss Communications SS7 Stack works with JDK1.5 and above (If using M3UA, JDK1.7 and above ). you will also need to have the following tools installed. Minimum requirement version numbers provided.
Subversion Client 1.4
: Instructions for using SVN, including install, can be found at http://subversion.tigris.org
Maven 2.0.9
: Instructions for using Maven, including install, can be found at http://maven.apache.org/
Ant 1.7.0
: Instructions for using Ant, including install, can be found at http://ant.apache.org
Downloading the source code
Use SVN to checkout a specific release source, the base URL is ?, then add the specific release version, lets consider 1.0.0.BETA10.
[usr]$ svn co ?/ss7-1.0.0.BETA10
Building the source code
Now that we have the source the next step is to build and install the source. JBoss Communications SS7 Stack uses Maven 2 to build the system. There are three profiles. Default one builds only java source. The other two profiles available "dahdilinux" and "dialogiclinux" additionaly compile native modules.
Native modules are supported only for linux OS for now.
Use "dahdilinux" profile if linux server on which this code is built already has dahdi module installed. Make sure you pass "include.zap" system property pointing to correct directory where dahdi is installed
[usr]$ cd ss7-1.0.0.BETA10 [usr]$ mvn install -Pdahdilinux -Dinclude.zap=/usr/include/dahdi
Use "dialogiclinux" profile if linux server on which this code is built already has dialogic module installed.
Make sure you pass "include.dialogic" and "include.dialogic.gctlib" system property pointing to correct directory where
dialogic libraries are installed. include.dialogic.gctlib points to directory where gctload
is present (generally
/opt/dpklnx for linux OS)
[usr]$ cd ss7-1.0.0.BETA10 [usr]$ mvn install -Pdialogclinux -Dinclude.dialogic=/opt/dpklnx/INC -Dinclude.dialogic.gctlib=/opt/dpklnx
To build JBoss Communications SS7 Stack without building any native libraries use
[usr]$ cd ss7-1.0.0.BETA10 [usr]$ mvn install
If you are using JBoss Communications SS7 Stack without any native dependencies, JBoss Communications SS7 Stack can run on any OS.
Use Ant to build the binary .
[usr]$ cd ss7-1.0.0.BETA10/release [usr]$ ant
Similar process as for Section 3.8.1, “Release Source Code Building”, the only change is the SVN source code URL, which is NOT AVAILABLE.